ENH: adds annotation filtering to raw figures #13425

DerAndereJohannes · 2025-09-17T18:38:23Z

Reference issue

Looking to solve issue #13325. Thank you to @larsoner for allowing me to go ahead with this enhancement.

What does this implement/fix?

This feature looks to add a convenience parameter in the plot function to automatically hide annotation labels that we are currently not interested in. For example, if we have a dataset that uses the ECG R peak as a response, this might make the stimulus triggers more difficult to see and slows down moving around the dataset due to additional computational cost.

To mitigate this, this pull request looks at adding a annotation_regex parameter which takes a regex as input and includes any matching annotation label in the view and hides the rest (default .* for all annotations).

The current version of this feature changes the current fig.mne.visible_annotations variable from setting True to everything, to setting True to only those annotation labels that fit the annotation_regex parameter.

This was the most logical place to put it as it deals with the initialization of fig.mne.visible_annotations, works with both qt and matplotlib backends and does not change the behaviour of the actual browser when you use it.

Additional information

I have set this pull request to be a draft, as I have just implemented the bare minimum to create the feature to see if where I am editing the code is implemented well. There is currently no documentation (Though this would be a quick add).

Example Code using the new feature

import mne

BACKEND = "qt" # "matplotlib"

mne.viz.set_browser_backend(BACKEND)

# Example dataset included in the mne repository
raw = mne.io.read_raw_brainvision("mne/io/brainvision/tests/data/test.vhdr")

raw.plot(block=True, annotation_regex="^Stimulus")

Example Images

All Triggers in a Matplotlib Browser

Triggers with Parameter `annotation_regex="^Stimulus"` in a Matplotlib Browser

Triggers with Parameter `annotation_regex="^Stimulus"` in a QT Browser

Let me know if I can supply anything else or if I am ok to add the documentation regarding the current code and change this to an actual pull request.

Thanks in advance!

welcome · 2025-09-17T18:38:26Z

Hello! 👋 Thanks for opening your first pull request here! ❤️ We will try to get back to you soon. 🚴

for more information, see https://pre-commit.ci

larsoner

Looks reasonable. Can you add a test? Or even better, modify an existing test (to save on testing time) and make sure that the set of annotations is indeed limited compared to the default show-all. And yes you can add doc/changes/devel/13425.newfeature.rst with the :newcontrib: role and a new entry in doc/changes/names.inc!

larsoner · 2025-09-17T18:54:53Z

mne/io/base.py

        color=None,
        bad_color="lightgray",
        event_color="cyan",
+        annotation_regex=".*",


Suggested change

annotation_regex=".*",

*,

annotation_regex=".*",

larsoner · 2025-09-17T18:55:46Z

mne/viz/raw.py

    color=None,
    bad_color="lightgray",
    event_color="cyan",
+    annotation_regex=".*",


If you're going to add it here (which is reasonable) we need to make everything kwarg-only (which we've been doing to functions bit-by-bit)

Suggested change

annotation_regex=".*",

*,

annotation_regex=".*",

larsoner · 2025-09-17T18:56:01Z

mne/io/base.py

            color,
            bad_color,
            event_color,
+            annotation_regex,


This and everything afterward should be passed as keywords like annotation_regex=annotation_regex,

DerAndereJohannes · 2025-09-18T09:51:53Z

Thank you very much for the fast response! I have applied the changes you have mentioned and added some sample tests. I have added the tests to the already existing test_plot_annotations, though I have also added additional invokations to creating a figure with plot. I decided to add an additional invokation to test the default (.*) as I wanted to do it on something that had at least 2 annotations. The second test filters out one of them. such that one of them is true and the other is false.

Let me know if I should make any additional changes to the documentation or if I should convert this to a real pull request.

Thanks!

Edit:
With the failed tests, it seems like the function I changed with coloring the annotations is also used by the ICA and other plotting functions. Should I also add annotation_regex to these functions along with their tests? I think the feature makes most sense in just the raw plot, but adding it to the others would give similar behaviour among plotting.

larsoner · 2025-09-22T18:34:38Z

With the failed tests, it seems like the function I changed with coloring the annotations is also used by the ICA and other plotting functions. Should I also add annotation_regex to these functions along with their tests? I think the feature makes most sense in just the raw plot, but adding it to the others would give similar behaviour among plotting.

Sure feel free to add it there! Would be nice for user consistency I think

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

…13350) Signed-off-by: Emmanuel Ferdman <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

…ols#13428) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

Co-authored-by: Eric Larson <[email protected]>

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Co-authored-by: Daniel McCloy <[email protected]>

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

…#13442) Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

for more information, see https://pre-commit.ci

…ython into annotation_regex

ica plot_sources

DerAndereJohannes · 2025-10-19T17:23:06Z

Sorry, just realised I merged instead of rebasing. Should I remake the request?

larsoner · 2025-10-20T15:09:51Z

Sorry, just realised I merged instead of rebasing. Should I remake the request?

At the end of the day we squash+merge, what's important to look correct is the "Files Changed"

https://github.com/mne-tools/mne-python/pull/13425/files

This looks wrong... so you can either force-push to your branch to fix it, or open a new PR, either way is fine!

DerAndereJohannes · 2025-10-23T21:45:32Z

Closing and moving this pull request here: #13460

ENH: adds annotation filtering to raw figures

d76c420

DerAndereJohannes requested review from agramfort, dengemann, drammock and mscheltienne as code owners September 17, 2025 18:38

[pre-commit.ci] auto fixes from pre-commit.com hooks

0f25754

for more information, see https://pre-commit.ci

DerAndereJohannes marked this pull request as draft September 17, 2025 18:58

larsoner reviewed Sep 17, 2025

View reviewed changes

ENH: Add Tests and Documentation for annotation_regex parameter

3c747ce

pre-commit-ci bot and others added 18 commits September 22, 2025 22:04

[pre-commit.ci] pre-commit autoupdate (mne-tools#13427)

936bfae

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

MAINT: Reenable mpl nightly (mne-tools#13426)

08ef1c7

FIX: Add on_few_samples parameter to core rank estimation (mne-tools#…

3fbf986

…13350) Signed-off-by: Emmanuel Ferdman <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

FIX, TST: Try to get test_export_epochs_eeeglab passing again (mne-to…

3e29187

…ols#13428) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

MAINT: Update code credit (mne-tools#13432)

51b6a5c

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

[pre-commit.ci] pre-commit autoupdate (mne-tools#13431)

34e2743

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

[pre-commit.ci] pre-commit autoupdate (mne-tools#13434)

4fdde3a

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

Add BDF export (mne-tools#13435)

61bc8b8

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

MAINT: Ensure full checkout is used (mne-tools#13439)

adc01cd

FIX: Update osf.io links to new format (mne-tools#13440)

231f224

Co-authored-by: Eric Larson <[email protected]>

[pre-commit.ci] pre-commit autoupdate (mne-tools#13443)

06d09de

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Use timezone-aware ISO 8601 for website timestamp (mne-tools#13347)

94d9871

Co-authored-by: Daniel McCloy <[email protected]>

ENH: Dont constrain fiducial clicks to mesh vertices (mne-tools#13445)

7fb19a1

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Bump github/codeql-action from 3 to 4 in the actions group (mne-tools…

f3c00cc

…#13442) Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Eric Larson <[email protected]>

MAINT: Deploy [circle deploy] [skip azp] [skip actions]

e2d4ebc

MAINT: Auth [skip azp] [skip actions]

96bef2a

MAINT: Restore PySide6 6.10.0 testing (mne-tools#13446)

3cfac64

ENH: adds annotation filtering to raw figures

dc2908e

pre-commit-ci bot and others added 4 commits October 19, 2025 18:28

[pre-commit.ci] auto fixes from pre-commit.com hooks

7fbdd75

for more information, see https://pre-commit.ci

ENH: Add Tests and Documentation for annotation_regex parameter

a3d61cd

Merge branch 'annotation_regex' of github.com:DerAndereJohannes/mne-p…

22c16c9

…ython into annotation_regex

ENH: Add Tests and Documentation for annotation_regex parameter in

82ab0ac

ica plot_sources

DerAndereJohannes mentioned this pull request Oct 23, 2025

ENH: adds annotation filtering to raw and ica source figures #13460

Merged

DerAndereJohannes closed this Oct 23, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

ENH: adds annotation filtering to raw figures #13425

ENH: adds annotation filtering to raw figures #13425

Uh oh!

DerAndereJohannes commented Sep 17, 2025

Uh oh!

welcome bot commented Sep 17, 2025

Uh oh!

larsoner left a comment

Uh oh!

larsoner Sep 17, 2025

Uh oh!

larsoner Sep 17, 2025

Uh oh!

larsoner Sep 17, 2025

Uh oh!

DerAndereJohannes commented Sep 18, 2025 •

edited

Loading

Uh oh!

larsoner commented Sep 22, 2025

Uh oh!

DerAndereJohannes commented Oct 19, 2025 •

edited

Loading

Uh oh!

larsoner commented Oct 20, 2025

Uh oh!

DerAndereJohannes commented Oct 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

ENH: adds annotation filtering to raw figures #13425

ENH: adds annotation filtering to raw figures #13425

Uh oh!

Conversation

DerAndereJohannes commented Sep 17, 2025

Reference issue

What does this implement/fix?

Additional information

Example Code using the new feature

Example Images

All Triggers in a Matplotlib Browser

Triggers with Parameter annotation_regex="^Stimulus" in a Matplotlib Browser

Triggers with Parameter annotation_regex="^Stimulus" in a QT Browser

Uh oh!

welcome bot commented Sep 17, 2025

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

larsoner Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

larsoner Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

larsoner Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

DerAndereJohannes commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner commented Sep 22, 2025

Uh oh!

DerAndereJohannes commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner commented Oct 20, 2025

Uh oh!

DerAndereJohannes commented Oct 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Triggers with Parameter `annotation_regex="^Stimulus"` in a Matplotlib Browser

Triggers with Parameter `annotation_regex="^Stimulus"` in a QT Browser

DerAndereJohannes commented Sep 18, 2025 •

edited

Loading

DerAndereJohannes commented Oct 19, 2025 •

edited

Loading